home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 051-075 / scopedisk57 / ipc / ipc.h < prev    next >
C/C++ Source or Header  |  1995-03-19  |  7KB  |  185 lines
  1. /*******************************************************************
  2.  *                                                                 *
  3.  *                           IPC.h                                 *
  4.  *                                                                 *
  5.  *           Inter-Process-Communication Message Format            *
  6.  *                                                                 *
  7.  *              Revision 0.1 -- 1988 April 30                      *
  8.  *                                                                 *
  9.  *         Copyright 1988 Peter da Silva & Peter Goodeve           *
  10.  *                      All Rights reserved                        *
  11.  *                                                                 *
  12.  *  This source is freely distributable, but should not be         *
  13.  *  modified without prior consultation with the authors.          *
  14.  *                                                                 *
  15.  *******************************************************************/
  16.  
  17. #ifndef EXEC_TYPES_H
  18. #include "exec/types.h"
  19. #endif
  20.  
  21. #ifndef EXEC_PORTS_H
  22. #include "exec/ports.h"
  23. #endif
  24.  
  25. /*** Item Reference block -- an arbitrary number of these may be
  26.    put in an IPCMessage ***/
  27.  
  28. struct IPCItem {
  29.     ULONG   ii_Id;      /* four character ID (normally);
  30.                            determines exact meaning of IPCItem IDs */
  31.     ULONG   ii_Flags;   /* upper 16 bits have standard meaning;
  32.                            lower 16 bits are message dependent */
  33.     ULONG   ii_Size;    /* size of data structure (zero if ii_Ptr is not
  34.                            actually a pointer to data) */
  35.     void   *ii_Ptr;     /* points to defined data structure (could be within
  36.                            message block if IE_Flags says so) -- also may be
  37.                            recast to other 32-bit value (e.g. Lock) */
  38.     };
  39.  
  40.  
  41.  
  42. /*** The basic IPCMessage block ***/
  43.  
  44. struct IPCMessage {
  45.     struct Message  ipc_Msg;
  46.         /* ..ln_Name field should be NULL
  47.             mn_Length will include IPC_Items array and any in-line data
  48.         */
  49.     ULONG   ipc_Id,                /* four character (or other) ID */
  50.             ipc_Flags;
  51.     UWORD   ipc_ItemCount;         /* number of items in array */
  52.     struct  IPCItem ipc_Items[1];  /* .. actual size as needed */
  53.     };
  54.  
  55.  
  56. /*************************************************************/
  57.  
  58. /* Flags set by client (tentative...): */
  59. /* -- may appear in either IPCItem or IPCMessage Flags field */
  60.  
  61. #define IPC_TRANSFER   0x08000000
  62.     /* Data block ownership may be transferred to server */
  63. #define IPC_NETWORK    0x04000000
  64.     /* The data in this block/message may be transmitted to
  65.        another machine */
  66. #define IPC_INMESSAGE  0x02000000
  67.     /* The data in this block/message is included in the message length */
  68.  
  69. /* Flags returned by server (ditto): */
  70.  
  71. #define IPC_NOTKNOWN   0x80000000
  72.     /* The server could not handle this block/message
  73.        (either because it did not understand the ID or
  74.        was unable to process it -- see the secondary flags */
  75. #define IPC_MODIFIED   0x40000000
  76.     /* The server modified the data, either within the
  77.        supplied data block(s) or -- if permitted -- by
  78.        replacing/removing the block pointer; again maybe
  79.        other flag bits should indicate the nature of
  80.        the modification */
  81.  
  82. /* valid for Item only: */
  83. #define IPC_SERVER_OWNED 0x10000000
  84.     /* The server owns this data Item -- either because it has
  85.        created it or because it took it over from the client
  86.        (in which case it clears IPC_TRANSFER, which must have
  87.        been set) */
  88.  
  89.  
  90. /* secondary flag bits (more to come...): */
  91.  
  92. #define IPC_CHECKITEM 0x00800000
  93.     /* associated with IPC_NOTKNOWN -- indicates that one or more
  94.        particular items caused the flag to be set */
  95. #define IPC_FAILED 0x00400000
  96.     /* IPC_NOTKNOWN flag was set because the server failed to
  97.        handle an ID that it is designed to (rather than just
  98.        not recognizing the block) */
  99.  
  100. /*************************************************************/
  101.  
  102.  
  103. /*** IPC Ports and Procedures ***/
  104.  
  105.  
  106. /* -- see IPCPorts.h for actual structure definitions */
  107. #ifndef IPC_PORTS_H
  108. /* Normal user doesn't need access to port components,
  109.    so just use a convenient define.  Note that an IPC port
  110.    is NEVER in private data space -- or in the public port
  111.    list -- it is created and managed by the package routines
  112.    only. */
  113. #define IPCPort MsgPort
  114. #endif
  115.  
  116.  
  117. /* IPC Port Handling function prototypes: */
  118.  
  119. struct IPCPort * FindIPCPort(char *);
  120.     /* returns pointer to port if it exists -- null otherwise;
  121.        registers a new connection to the port */
  122.  
  123. struct IPCPort * GetIPCPort(char *);
  124.     /* returns pointer to port -- it is created if it doesn't exist;
  125.        registers a new connection to the port */
  126.  
  127.  
  128. void UseIPCPort(struct IPCPort *);
  129.     /* adds a connection to a port (passed by pointer from another
  130.        process) */
  131.  
  132.  
  133. void DropIPCPort(struct IPCPort *);
  134.     /* disconnect from port -- port will be destroyed if there are
  135.        no other connections left */
  136.  
  137.  
  138. struct IPCPort * ServeIPCPort(char *);
  139.     /* become a server for the named port (created if it doesn't exist);
  140.        null is returned if the port already has a server, otherwise a
  141.        pointer to it is returned */
  142.  
  143. void ShutIPCPort(struct IPCPort *);
  144.     /* (server only) prevent more messages being sent to this port, but
  145.        do not end server connection; remaining messages can be dealt
  146.        with before Leaving */
  147.  
  148. void LeaveIPCPort(struct IPCPort *);
  149.     /* cease to be a server for this port; another process can then
  150.        become a server if it desires */
  151.  
  152. CheckIPCPort(struct IPCPort *, USHORT);
  153.     /* returns number of current connections to this port (including
  154.        server); a call by the server (only) will also set the (user
  155.        settable) port flags to the value in the second argument --
  156.        currently the only valid flag is IPP_NOTIFY */
  157.  
  158.  
  159. PutIPCMsg(struct IPCPort *, struct IPCMessage *);
  160.     /* sends an IPCMessage to an IPCPort; if the port has no server or
  161.        is shut, the message is not sent and the function returns FALSE;
  162.        otherwise it returns TRUE. (Other port flags to be added later
  163.        may affect these actions.) */
  164.  
  165. struct IPCMessage * CreateIPCMsg(int);
  166.     /* creates a standard IPCMessage block (in MEMF_PUBLIC) with the
  167.        number of IPCItems supplied as argument ( special cases -- like
  168.        in line data -- you will have to handle yourself, and you always
  169.        have to manage the data blocks yourself). */
  170.  
  171.  
  172. void DeleteIPCMsg(struct IPCMessage *);
  173.     /* deletes a standard IPCMessage block;  you must first have disposed
  174.        of any attached data as appropriate */
  175.  
  176.  
  177. /* Server settable Port flags: */
  178.  
  179. #define IPP_NOTIFY 0x0001
  180.     /* server wants to be signalled if connection is added or dropped
  181.        (the port sigbit is used to signal the task,
  182.         but no message is sent) */
  183.  
  184. /*************************************************************/
  185.